BOSS Masterlist Syntax Readme

Contents

1. Introduction
2. Structure
3. Formats
   1. Format Support
   2. Format Comparison
4. Rules & Guidelines
5. Common Functionality
   1. Plugin Lines
   2. Silent Comments
   3. Message Lines
   4. Group Lines
   5. Legacy Conditionals
6. MF2-Specific Functionality
   1. Regular Expression Plugin Matching
   2. Masterlist Variables & Variable Lines
   3. Global Messages
   4. General Conditionals
      1. Compound Conditionals
      2. Conditional Message Shorthand
7. Examples

Introduction

This documentation is a complete record of all information on the masterlist syntax, including rules and guidelines on usage, detailed explanations of features and syntaxes, and examples of usage. It is intended for use by BOSS developers and interested third party developers rather than as a document that should be read by users.

Third party developers will may find this documentation useful, but should be aware that there is an API available for accessing BOSS's masterlist and userlist information. See the BOSS API ReadMe.html document for more information.

Structure

The masterlist is a plain text file encoded in UTF-8 which lists mod plugins, which are files with .esp or .esm extensions, in the order in which they co-exist best in. Each plugin may optionally have one or more messages attached to it for display in the BOSS Log. To make managing the masterlist easier, mods are often placed in groups that are often themed. These groups are defined and named in the masterlist, and also provide some sorting functionality for BOSS's User Rules feature.

The masterlist is parsed (read) by BOSS line-by-line, so it is most useful to analyse the structure by the different types of line present:

• A line that defines a plugin's position is a plugin line. In their most basic form, these lines only contain the plugin's filename.
• A line that contains a message to be attached to a plugin is a message line. In their most basic form message lines contain a type identifier, which tells BOSS what type of message the line contains, and a string of characters which is the message itself. Message lines are positioned below the plugin line of the plugin they attach messages to.
• A line that defines the start and end point of a group is a group line.

A simple example of this structure is: [group line (start)] [plugin line] [plugin line] [message line] [message line] [plugin line] [group line (end)]

Formats

As BOSS has developed, so too has the masterlist format. There are currently two major revisions of the masterlist format, MF1 and MF2 (MF = Masterlist Format), and minor revisions of the second.

MF1 provides all of BOSS's basic functionality, while MF2 provides an alternative syntax for that same functionality while also extending and generalising it to give BOSS new capabilities.

Format Support

The table below displays which versions of BOSS are compatible with which masterlist formats.

If a version of BOSS does not recognise the syntax in which a line is written, it will assume that it is a plugin line, and so the line will effectively be ignored. This means that a masterlist may contain a mix of format syntaxes without issue.

Format Comparison

The table below gives a quick overview of the differences between the masterlist formats.

Rules & Guidelines

The following are some rules and guidelines that should be followed when editing the masterlist.

1. When a web link is included in a message, enclose it in double quotes "", for example: www.example.org should be written "www.example.org". BOSS will automatically turn web links into hyperlinks in the HTML BOSS Log.
2. Don't include any HTML (or BBCode) formatting in messages.
3. Don't duplicate lines using different syntaxes. A line only needs to be written in one syntax.
4. As the majority of BOSS users use versions that only support MF1, write in that where possible.
5. If using MF2.x, write the keywords in uppercase and indent message lines by one space.
6. Write plugin names in the correct case (ie. capital letters where the plugin has capital letters). Some people use BOSS on Linux, which is case-sensitive.
7. Use blank lines to separate plugins that are grouped together or where it helps readability.
8. Use silent comments when something may need clarification to others reading the masterlist (such as when a plugin looks like it is misspelled, but is correct).
9. Only make edits/additions you're confident about - otherwise discuss the issue on the official forum threads.
10. If you're unsure on how to write something in the correct syntax, check the masterlists for examples, and don't be afraid to ask other team members for help.
11. When you list Bash Tags for a plugin, separate them using ", " and not just ",". Eg. {{BASH: Graphics,NoMerge}} should be written {{BASH: Graphics, NoMerge}}. This improves readability in the BOSS Log and the masterlist itself.

Common Functionality

This section details the syntaxes for functionality found at least partially in all masterlist formats.

Plugin Lines

Plugin lines have the simplest of syntaxes. The line should contain only the plugin filename: [plugin]

In MF2: Plugin lines also have a keyword associated with them, MOD, which can be given before the plugin filename and the two separated by a colon. However, since BOSS assumes that lines with no recognised keywords are plugin lines, the inclusion of the keyword is unnecessary and for backwards-compatibility should not be used unless a conditional is used in the plugin line. If the plugin line has a conditional, the MOD keyword should be included between the conditional and the colon. Alternatively, both the keyword and the colon may be omitted, but as the colon is an absolute requirement for all other parts of MF2 syntax, this is not good practice. The choice available is a side-effect of backward compatibility with MF1.

Silent Comments

Silent comments are character strings that are skipped by the BOSS parser and so have no effect on BOSS's output. C++ style comments must start at the beginning of a line. C style comments must start and end at the beginning of lines. Comments may not be used inline. In the table below, [comment] is the comment being made.

Message Lines

Message lines are listed under the plugin line of the plugin that they are to be attached to. There are several different types of message line, with not all being available in all syntaxes. In the table below, [message] is the message to be attached. Messages have no special syntax unless otherwise noted.

The above table references some Oblivion mods. The table below gives the Fallout 3 and Fallout: New Vegas equivalents. Replace all references in the above table with the relevant equivalents below for the game in question. The masterlist variables listed are conditionally defined at the top of the relevant games' masterlists if the user has the corresponding mods installed and are used by the MF2 mod-specific messages. In MF1, the checks are hardcoded into BOSS.

Group Lines

As mentioned before, groups are used to provide some order in the masterlist and to allow bulk plugin sorting via User Rules. A group is defined by start and end lines which enclose the plugins to be contained in the group.

In the table above, [name] is the name of the group.

In MF1: The name is only given at the start of a group, not the end.
In MF2: The name should be given at both the start and the end, although inclusion at the end is not an absolute requirement. If an ending line does not contain a group name, it does not require a colon.

Legacy Conditionals

MF1 supports only two specific conditionals other than the plugin-specific messages given earlier, while MF2 supports a generalised conditional expression. The specific conditionals written in both syntaxes are given in the table below, where [line] is the rest of the line's contents.

While the above table references FCOM, the functionality is not Oblivion-specific. Use the mod/variable table in the Message Lines section to find the equivalent mods for other games.

Conditionals can be put before any plugin or message line, and the line will only be processed if the conditional is true. Conditionals must not be added to group lines.

In BOSS v1.7+, if a conditional attached to a plugin is false, all the messages for that plugin will also be skipped. However, to ensure compatibility with older versions, if a conditional is added to a plugin line, it should also be added to all message lines following it.

In MF2: Conditionals are subject to the requirement of a colon marker :, but it goes after the line's keyword. IF ($FCOM) MOD: Mart's Monster Mod.esm IF ($OOO) SAY: Make sure you're using "Mart's Monster Mod for OOO.esm" too.

MF2-Specific Functionality

This section details the syntax for functionality only available using MF2. Unless otherwise noted, all functionality is present in MF2.0.

A colon : must be put after the last keyword on a line, before the plugin or group name or message that follows it, to mark the boundary. The message and group line keywords given in the previous section had colons included, however they are really separate things as will become clear through the course of this section.

Regular Expression Plugin Matching

This is MF2.1 functionality.

Regular expressions may be used in the masterlist for plugin names using the following syntax, where [regular expression] is the plugin filename written in regex syntax: REGEX: [regular expression]

The regex syntax used is POSIX Extended. BOSS will search the user's plugins and sort all the plugins that match the regular expression given in its location in the masterlist. If more than one plugin matches, the order in which the plugins will be placed at that position is random, so it should not be used to sort a set of similarly named plugins which require specific ordering within the set.

Masterlist Variables & Variable Lines

Variables may be defined in the masterlist using the following syntax, where [name] is the variable name: SET: [name]

The name of a variable is an alphanumerical string that should not contain spaces. The definition of variables may be queried in conditionals. Variables may only be defined, it is not possible to 'undefine' a variable. (In that respect they are constants with indeterminate unique values rather than variables, but they are referred to as variables here.)

Unlike message lines, variable lines exist independently of plugin lines. A variable line will therefore signal the termination of a set of attached message lines, much like a plugin line would, and any message lines after the variable line will be skipped, having no plugin to attach to. For example: [plugin line] [message line 1] [message line 2] [variable line] [message line 3]

In the above structure, only message lines 1 and 2 will be parsed, and message line 3 will be ignored.

Global Messages

A global message may be printed to the BOSS Log using the following syntax: GLOBAL [message keyword]: [message]

Where the [message keyword] and [message] are as described in the above Message Lines section. The message will be printed to the BOSS Log in a separate General Messages section above the list of recognised plugins.

General Conditionals

Conditionals in MF2 are expressions that can be added to the start of any plugin or message line, but not group lines. Conditionals evaluate to true or false with the following effects:

• True: The line will be parsed as if the conditional were not there.
• False: If the line is a message or variable line, the line will be skipped as if it did not exist. If the line is a plugin line, the plugin and all the message lines immediately following it will be skipped.

There are two types of conditional: one that tests if the condition it contains is true, and one that tests if the condition it contains is false. The table below gives their syntaxes, where [line] is the rest of the line.

Note: If [line] is a plugin line, then the conditional must be followed by the MOD keyword, eg. IF ($OOO) MOD: MyPlugin.esp will place MyPlugin.esp in that position if OOO is installed.

There are four types of condition that can be tested for within a conditional. These types and their syntaxes are described in the table below.

Note: Regular expression conditions are not supported in MF2.1 and below.

Filenames, regular expressions and checksums are case-insensitive. Version strings and masterlist variables are case-sensitive.

A [file] may be any type of file. For mod and Script Extender plugins, only the filename should be given, as BOSS assumes they are installed in the correct locations. For all other files, the starting folder is Data, eg. the correct syntax for a texture would be Textures\testtexture.dds. Version checks will only work for files with the extensions .esp, .esm, .dll or .exe. Paths may use either forwardslashes or backslashes.

A [regular expression] is a [file] written as a regular expression, using the POSIX Extended syntax. Any parent paths given must not contain any regular expression syntax other than the escaping of any backslashes, i.e. Textures\\testtexture(_n)?\.dds is valid but Te[xX]tures\\testtexture(_n)?\.dds is not. Like [file], mod and Script Extender plugins should only have their filenames given, and the starting folder for all other files is Data. The file placeholders given below must not be used in regular expressions.

In addition to explicitly referencing files, there are a few placeholders that can be used to reference certain files, given in the table below:

Paths are given from the Data folder.

Note that conditional evaluation can have a noticeable impact on BOSS's execution time. In order of decreasing speed:

1. Variable conditions: These are very fast as BOSS stores defined masterlist variables in a hash set while running.
2. File conditions: These are still fast, and should not impact performance. However, repeated usage may cause slowdown as file existence is not stored in memory and is re-checked for every condition.
3. Regular expression conditions: These are of variable speed, but will always be slower than file checks. They need to scan a directory's contents for any files that match the given regex, so the processing time will vary with the number of files to be scanned.
4. Version conditions: These are of a medium speed. They need to read part of a file's contents to extract its version and so are slower than file conditions. Like file existence, version information is not stored in memory.
5. Checksum conditions: These are very slow, though processing time varies with file size. They require a complete read of a file and calculate the CRC from its contents. Usage will result in noticeable slowdown. Calculated CRCs are stored in hash maps while running so that a plugin's CRC is only calculated a maximum of once. Subsequent checks will be faster than file checks but still slower than variable checks.

In order to reduce the effect of conditional evaluation on BOSS's execution time, efficient use of conditionals is required. For example, the following: IF (=1.2|Mod1.esp) MOD: Mod2.esp IF (=1.2|Mod1.esp) MOD: Mod3.esp IF (=1.2|Mod1.esp) MOD: Mod4.esp IF (=1.2|Mod1.esp) MOD: Mod5.esp

is better written as: IF (=1.2|Mod1.esp) SET: Mod1Correct IF ($Mod1Correct) MOD: Mod2.esp IF ($Mod1Correct) MOD: Mod3.esp IF ($Mod1Correct) MOD: Mod4.esp IF ($Mod1Correct) MOD: Mod5.esp

as this reduces the level of computation required. The difference will probably not be noticeable for a small number of conditionals like above, but the masterlists contain tens of thousands of lines which are all potentially conditional. BOSS evaluates all conditionals as it cannot know which will have an effect on load order at parsing time.

Compound Conditionals

Compound conditionals can be formed by combining two or more conditionals using logical AND or OR operators. The conditionals are evaluated incrementally in the order they are read. This means that the operators operate on everything to the left of them as a whole, and the first conditional on their right. For example,

where A, B, C and D are all individual conditionals, is evaluated as ((A && B) || C) && D, not (A && B) || (C && D)

Conditional Message Shorthand

This is MF2.1 functionality with MF2.2 extensions.

In MF2.1: The shorthand can only be used by MF2 incompatibility and requirement messages; , cannot be used to separate items; checksum, variable and regular expression conditions cannot be used at all; incompatibility messages cannot use version checks.

While conditionals can be used to make messages appear in a user's BOSS Log only under certain circumstances, the implementation described above is unsuitable for lists of independent mods such as those found in incompatibility and requirement messages as to cover all combinations would require several message lines.

To resolve this issue, a shorthand is provided for generating messages where each item's display is independently conditional. The shorthand goes in place of the [message] used in the syntax explained by the Message Lines section above and is as follows: "[comparator][version 1]":"[file 1]"="[mod 1]" | [checksum 2]:"[file 2]"="[mod 2]" | "[comparator][version 3]":"[file 3]" | [checksum 4]:"[file 4]" | "[file 5]" | "[file 6]"="[mod 6]" | $[variable 7]="[mod 7]" | r"[regular expression 8]"="[mod 8]"

Each item in the list is separated by a | or , character (the latter not shown above). There is no limit to the number of items that may be listed. [file], [comparator], [version], [variable], [checksum] and [regular expression] are all defined as in the General Conditionals section above. [mod] can be any string of characters not containing double quote characters ", though as the name suggests it is intended to be the name of the mod that the plugin tested for belongs to.

As with all message lines, a conditional may also be prepended before the keyword, if the whole message is conditional on something.

Each item in the shorthand is evaluated as follows:

• If "[file]" is given and
  • "[comparator][version]": is given then the item's condition is [comparator][version]|"[file]".
  • [checksum]: is given then the item's condition is [checksum]|"[file]"
  • neither "[comparator][version]": nor [checksum]: are given then the item's condition is "[file]"
• If $[variable] is given then that is the item's condition.
• If r"[regular expression]" is given then that is the item's condition.

For requirement messages:

• If the item's condition evaluates to false, the item will be displayed in the BOSS Log message.
• If the item's condition evaluates to true, the item will not be displayed in the BOSS Log message.

For incompatibility messages (and other message types):

• If the item's condition evaluates to true, the item will be displayed in the BOSS Log message.
• If the item's condition evaluates to false, the item will not be displayed in the BOSS Log message.

How the item is displayed in the BOSS Log depends on whether "[mod]" is given in the item or not. If:

• ="[mod]" is given: [mod] will be printed in the message.
• ="[mod]" is not given: [file] will be printed in the message.

Note that if the item contains $[variable] or r"[regular expression]", it must also contain ="[mod]". If no items are printed in the message, then the message itself will not be displayed. The format of the output is

• Incompatible with: "[mod 1]", "[file 2]"

or

• Requires: "[mod 1]", "[file 2]"

Examples

Below are some examples of the syntaxes covered in this documentation. The examples use some real plugins, but the content is purely exemplary and does not necessarily contain any valid information. IF (<1.8|"BOSS") GLOBAL ERROR: An update to BOSS is available. Please download BOSS v1.8. //OOO installed. This is a standard variable, but it's OK to re-define it. //We can indent this comment because in MF2 whitespace doesn't matter, so it looks like it's at the start of the line. IF ("Oscuro's Oblivion Overhaul.esm") && IF("Oscuro's Oblivion Overhaul.esp") SET: OOO Mart's Monster Mod for OOO.esm IFNOT ($OOO) WARN: Oscuro's Oblivion Overhaul.esm missing. Re-install OOO. //The above line will only be shown in the BOSS Log if OOO is not installed correctly. Unofficial Oblivion Patch.esp IF (<3.3|"Unofficial Oblivion Patch.esp") SAY: Upgrade to the latest version of the Unofficial Oblivion Patch Supplementals, found here: "http://tes.nexusmods.com/downloads/file.php?id=27710" TAG: {{BASH: Relev}} and [NoMerge]. Wrye Bash will automatically add the Relev tag and remove the NoMerge tag for you. IF (CACF51FC|"FastExit2.dll") ? You have a legitimate copy of Fast Exit 2 installed. Good on you! All Natural.esp IF (>0.0.20.0|"OBSE") WARN: You have the correct version of OBSE installed. Unofficial Shivering Isles Patch.esp IF (E0DDDD00|"Unofficial Oblivion Patch.esp") SAY: You are using version 3.3.5 of the UOP. //The given checksum is the checksum of v3.3.5, as calculated by BOSS. IF (=4.1.0.0|"sr_Oblivion_Stutter_Remover.dll") SAY: You have Oblivion Stutter Remover v4.1 installed. \Comment out the below section. /* PluginNotParsed.esp & {{BASH: Graphics}} You'll never see this in your BOSS Log. */ //'FCOM' is a standard variable. IF ($FCOM) MOD: Mart's Monster Mod - Fran's Leveled Quests.esp >* Delete. Already integrated into FCOM. //We can mix 'n' match MF1 and MF2 syntaxes. Also, all the silent comments for messages are not on the message line, as otherwise they'd be counted as part of the message.

Assuming that all version and plugin conditionals evaluate to true apart from the first, the above would have the following output.

• Mart's Monster Mod for OOO.esm
• Unofficial Oblivion Patch.esp
  • Note: Upgrade to the latest version of the Unofficial Oblivion Patch Supplementals, found here: http://tes.nexusmods.com/downloads/file.php?id=27710
  • Bash Tag suggestion(s): {{BASH: Relev}} and [NoMerge]. Wrye Bash will automatically add the Relev tag and remove the NoMerge tag for you.
  • Note: You have a legitimate copy of Fast Exit 2 installed. Good on you!
• All Natural.esp
  • Warning: You have the correct version of OBSE installed.
• Unofficial Shivering Isles Patch.esp
  • Note: You are using version 3.3.5 of the UOP.
  • Note: You have Oblivion Stutter Remover v4.1 installed.
• Mart's Monster Mod - Fran's Leveled Quests.esp
  • ERROR: Delete. Already integrated into FCOM.

License

This document is part of the BOSS documentation.
Copyright (C) 2011 BOSS Development Team.
See the file BOSS ReadMe.html for copying conditions.